Home | Printable Version
9: JavaScript APIs
Table - The following WebMaker Script APIs are used by the built-in Visibility and Events management processing in WebMaker. You can use these APIs if you need to customise and include additional functionality for your applications:
Function Parameters/Returns and Notes
Get and Set Fields  
hyf.util.getFieldValue(fieldName, getDisplayValue); Attempts to get the current value for the given field. This will attempt to determine the type of the given field name, by checking dojo widgets, any form elements, and display only containers with the given control id.
  fieldName - The name of the field to get the value for.
  getDisplayValue (Optional) - If provided and set to true, the returned value will be the displayed value for the control rather than the underlying data value where appropriate (e.g. for select controls).
  RETURNS: A string containing the current value, or null if the field couldn't be found. For multiple selection controls, an array of all current values will be returned.
hyf.util.setFieldValue(fieldName, fieldValue); Attempts to set the current value for the given field. This will attempt to determine the type of the given field name, by checking dojo widgets, any form elements, and display only containers with the given id. If the field supports multiple selections, then the provided value will be added in addition to any others that already exist.
  fieldName - The name of the field, which contains the value that is required.
  fieldValue - The value to set.
  RETURNS: None
Validation  
hyf.validation.validateForm(); Validates all fields on the whole page, and shows any errors found using the error display options specified for the page. For further information you can reference the following Forum entry.
  RETURNS: boolean (true or false) indicating the outcome of the validation.
hyf.validation.validateContainer(container); Validates all fields within a container, and shows any errors found using the error display options specified for the page.
  field - A Group component (e.g. HTML div) on the page. All fields within this container will be validated.
  RETURNS: boolean (true or false) indicating the outcome of the validation.
hyf.validation.validateField(field); Validates the specified field, and will display an error if appropriate.
  field - The Field component (e.g. text box) on the page that should be validated.
  RETURNS: boolean (true or false) indicating the outcome of the validation.
Error Handling  
hyf.FMAction.getErrorDisplay().addError(error); Tells the page about a new custom error that should be displayed the next time validation is performed. For further information you can reference the following Forum entry.
  error - A ValidationError object describing the error. You create a ValidationError object using the field in error, and the relevant error code, e.g. new hyf.validation.ValidationError(errorField, errorCode);
hyf.validation.DisplayMessages.addMessageProducer(func, errorCode); Tells the built in validation process about a new function that can be used to return custom error messages for display. For further information you can reference the following Forum entry.
  func - The function name reference to call. When called, this function will be passed two parameters, the Field (e.g. a text box) in error, and the code indicating the type of error.
  errorCode - (Optional) - The particular error code that this function returns messages for. If omitted, the function will be called for all errors.
Date Processing  
hyf.calendar.setDateConstraint(fieldName, restrictionType, restrictionValue, repeatId); Sets data constraints on a date field to restrict the values that can be entered. For further information you can reference the following Forum entry.
  fieldName - The name of the date field to restrict.
  restrictionType (Optional) - Set to Minimum or Maximum
  restrictionValue - Sets the restriction value applied. This can be one of the supported keywords (Today, Yesterday, Tomorrow, LastWeek, NextWeek, LastMonth, NextMonth, LastYear, NextYear), or the name of another date field whose value should be used, or a date value string. If a date value is provided, this should be in the data date format for the field.
  repeatId (Optional) - If the fieldName is in a repeating table, then the repeat Id of the specific field to constrain should be provided. This will consist of the repeat name and the row identifier e.g. orderTable4. The repeat name can be found by clicking on the repeat container when in Design Mode on the Page Design screen. Note: To constrain all the field entries in a repeat, use the hyf.calendar.setRepeatDateConstraint function.
hyf.calendar.setRepeatDateConstraint(repeatName, fieldName, restrictionType, restrictionValue, restrictionValueFieldInRepeat); This supports setting of the appropriate constraint for a date field within a repeat structure (e.g. table). This ensures the constraint is applied to the date field for each repeat entry (row).
  repeatName - The name of the repeat the date field is contained within. This name can be found by clicking on the repeat container when in Design Mode on the Page Design screen.
  fieldName - The name of the date field to restrict.
  restrictionType (Optional) - Set to Minimum or Maximum
  restrictionValue - Sets the restriction value applied. This can be one of the supported keywords (Today, Yesterday, Tomorrow, LastWeek, NextWeek, LastMonth, NextMonth, LastYear, NextYear), or the name of another date field whose value should be used, or a date value string. If a date value is provided, this should be in the data date format for the field.
  restrictionValue FieldInRepeat - (Optional) - If set to true, then the restrictionValue is assumed to be the name of a date field within the same repeat as the field being restricted, and the appropriate repeat ID is automatically added to ensure each field being restricted is based on the field in the same repeat row.
Display Control  
hyf.util.hideComponent(component, animate); Hides the specified component to ensure it is no longer visible on screen.
  component - The Group component (e.g. a HTML div) to hide.
  animate (Optional) - Boolean (true or false) indicating whether the hiding of the component should be animated or not. Defaults to false, if omitted.
hyf.util.showComponent(component, animate); Ensures the specified component is visible on the screen.
  component - The Group component (e.g. a HTML div) to show.
  animate (Optional) - Boolean (true or false) indicating whether the showing of the component should be animated or not. Defaults to false, if omitted.
hyf.util.toggleComponent(component, method, animate); Toggles the display of the specified component.
  component - The Group component (e.g. a HTML div) to show/hide.
  method (Optional) - String specifying the required visibility of the component (show or hide). If omitted, or set to null, the current state will be toggled. If the value is specified, it will switch to that state if it is not already in that state.
  animate (Optional) - Boolean (true or false) indicating whether the showing of the component should be animated or not. Defaults to false, if omitted.
hyf.util.getMouseCoords(evt); Returns the coordinates of the mouse for the supplied event.
  evt - The event object, for which the mouse coordinates are required. In custom JavaScript event actions, this is available as objEventSource.event.
  RETURNS: An object containing two properties (x and y) indicating the mouse location.
hyf.util.getComponentPosition(component, screen); Returns the current location coordinates of the specified component.
  component - The Group component (e.g. an HTML div), for which the position is required.
  screen (Optional) - Boolean (true or false) value. If set to true, the returned values are in screen coords, i.e. they are adjusted for scrollable regions, to allow comparison with the mouse coordinates returned from the getMouseCoords method.
  RETURNS: An object containing 4 properties: x, y, width and height. The x and y values indicate the position of the top left corner of the component.
Form and Ajax Submission  
hyf.FMAction.handleFormSubmission(actionParam, validateParam, objEventSource) Performs a full page submission of the form. Example: hyf.FMAction. handleFormSubmission( {name: 'Action', option: 'Static', value: 'my_action'}, {name: 'Validate', option: 'Static', value: 'true'}, objEventSource)
  actionParam - Specifies the action to call. Supported option types: 'Static'
  validateParam - Indicates whether to validate first. Supported option types: 'Static'
  RETURNS: Boolean (true or false), indicating whether the form was submitted.
hyf.FMAction.handleAjaxSubmission(actionParam, sourceParam, targetParam, validateParam, objEventSource) Performs an Ajax Partial Page submission of some data. Example: hyf.FMAction. handleAJAXSubmission( {name: 'Action', option: 'Static', value: 'my_action'}, {name: 'Source', option: 'AllFormData', value: ''}, {name: 'Target', option: 'PageGroup', value: 'my_group_name'}, {name: 'Validate', option: 'Static', value: 'true'}, objEventSource)
  actionParam - Specifies the action to call. Supported option types: 'Static'
  sourceParam - Indicates whether to send all the data on the page or just the data within a particular group. Supported option types: 'AllFormData', 'PageGroup'
  targetParam - Identifies the group, where the results should be placed. Supported option types: 'PageGroup'
  validateParam - Indicates whether to validate first. Supported option types: 'Static'
  RETURNS: Boolean (true or false), indicating whether the partial page was submitted. Note: Partial Page submissions are fired independently. As a result, it is not possible to confirm completion. In some situations you may need to check that it has completed successfully. Please refer to the Customising the Generated Ajax Calls Forum entry.
Themes - SASS and CSS Styling Design using Data Sources